===================================
 Docutils: Documentation Utilities
===================================
---------------------------------------------------------
 Written in Python, for General- and Special-Purpose Use
---------------------------------------------------------

Docutils is an open-source text processing system for processing
plaintext documentation into useful formats, such as HTML, LaTeX,
man-pages, open-document or XML.
It includes reStructuredText_, the easy to read, easy to use,
what-you-see-is-what-you-get plaintext markup language.

----------------------------------------------------------------------

Overview
========

**To get up & running quickly**, see the Quick-Start_ section of the
README_ file.

All **documentation** can be reached from the `Docutils Project
Documentation Overview`_.

To the developers of an open source project, **feedback** is a great
motivator and is very welcome.  We also rely on feedback for
determining what features to implement.  Thus, if you tell us what you
need, you may just get it!  Please post any feedback to the
Docutils-users_ mailing list.

All **discussion** about Docutils takes place on the `mailing lists`_.

If you find a **bug**, please file a `bug report`_ or send email to
the Docutils-users_ mailing list.  **Patch** submissions should be
filed in the `patch tracker`_ (preferred) or sent to Docutils-develop_
(where you will be asked to send them to the `patch tracker`_).

We welcome all kinds of **contributions**.  There's a `To Do list`_
full of interesting ideas awaiting a champion.  If you have any
questions regarding how to extend Docutils, please feel free to ask on
the Docutils-develop_ mailing list.

.. NO DONATE on new sf platform
   Please also consider **donating** to Docutils: |donate|.

The only **requirement** for running Docutils is Python_ 2.4 or later.
(For Docutils 0.5, Python 2.2.1+ is required.
Up to Docutils 0.4, Python 2.1 is required.)
From version 0.6, Docutils is compatible with Python 3 (see README_ for
details).

Docutils is in active development and APIs should be considered 
**experimental** subject to change at any time.  Although *any time* is a time 
after serious thought and discussion.


Download
========

.. Note::

   Snapshots are supported by sourceforge directly.
   The whole trunk is packed docutils, sandbox, prest/perl and web:

     https://sourceforge.net/p/docutils/code/HEAD/tarball

   or only the docutils package:

     http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/

  Click the download snapshot button.

  The snapshosts listed below are created on website updates.     

We recommend that you use a snapshot_ from `Docutils' Subversion
repository`_. The snapshots usually contain *more features* and *fewer bugs*
than the "official" releases |---| they're not only for developers!

The latest **release package** is `docutils-0.12.tgz`__.  It was
released on 2014-07-06 and is mostly intended for distributors.  See
the `release notes`_ for a list of changes since the previous release
(0.11).

__ http://prdownloads.sourceforge.net/docutils/docutils-0.12.tar.gz?download
.. _release notes: RELEASE-NOTES.html#release-0-12-2014-07-06

The Sandbox_ contains experimental, contributed code. You can download a
complete `snapshot of the Sandbox`_ or `browse the Sandbox`_ to download a
subset.

.. class:: credits

Web site, tracker and mailing lists and subversion repository hosted by |SourceForge|_.
Powered by |Python|_.

.. class:: hidden

Google should index the mailing lists: `Docutils-users
<http://news.gmane.org/group/gmane.text.docutils.user/last=/force_load=t>`__,
`Docutils-develop
<http://news.gmane.org/group/gmane.text.docutils.devel/last=/force_load=t>`__,
and `Docutils-checkins
<http://news.gmane.org/group/gmane.text.docutils.cvs/last=/force_load=t>`__.

.. |---| unicode:: U+02014 .. em dash
   :trim:
.. _Deploying Docutils Securely: docs/howto/security.html
.. _Docutils sprint:
   http://wiki.python.org/moin/PyCon2006/Sprints/DocutilsSprint
.. _PyCon 2006: http://us.pycon.org/TX2006/HomePage
.. _dugui: http://docutils.sourceforge.net/sandbox/dugui/
.. _LaTeX math support:
   http://docutils.sourceforge.net/sandbox/latex_directive/

.. _snapshot:
   http://docutils.sourceforge.net/docutils-snapshot.tgz
.. _snapshot of the Sandbox:
   http://docutils.sourceforge.net/docutils-sandbox-snapshot.tgz
.. _browse the Sandbox:
   http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/

.. _bug report: http://docutils.sourceforge.net/BUGS.html
.. _patch tracker: http://sourceforge.net/p/docutils/patches/
.. _mailing lists: docs/user/mailing-lists.html
.. _Docutils-users: docs/user/mailing-lists.html#docutils-users
.. _Docutils-develop: docs/user/mailing-lists.html#docutils-develop
.. _sandbox: sandbox/README.html
.. _reStructuredText: rst.html
.. _project files page:
   http://sourceforge.net/project/showfiles.php?group_id=38414
.. _To Do list: docs/dev/todo.html
.. _README: README.html
.. _Quick-Start: README.html#quick-start
.. _Docutils Project Documentation Overview: docs/index.html
.. _Docutils' Subversion repository: docs/dev/repository.html
.. |donate| image:: http://images.sourceforge.net/images/project-support.jpg
   :target: http://sourceforge.net/donate/index.php?group_id=38414
   :align: middle
   :width: 88
   :height: 32
   :alt: Support the Docutils project!
.. |SourceForge| image::
   http://sourceforge.net/sflogo.php?group_id=38414
   :alt: SourceForge Logo
   :align: middle
   :class: borderless
   :width: 88
   :height: 31
.. |BerliOS| image::
   http://developer.berlios.de/sflogo.php?group_id=2920
   :alt: BerliOS Logo
   :align: middle
   :class: borderless
   :width: 124
   :height: 32
.. |Python| image:: python.png
   :alt: Python Logo
   :align: middle
   :class: borderless
   :width: 193
   :height: 32
.. _BerliOS: http://developer.berlios.de/
.. _SourceForge: http://sourceforge.net/
.. _Python: http://www.python.org/



..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End:
